Inside Macintosh: QuickDraw GX Programmer's Overview / Part 2 - The QuickDraw GX Programming Cookbook

Chapter 8 - Printing

Managing Printing Information

This programming recipe creates a job object to store printing-related information for a document and keeps the job object updated when the
user puts your application in the background.

Overview of Recipe Steps

The steps in this recipe show you how to:

1. Store printing information in your document information structure
2. Create a job object for your document
3. Update the job object in response to resume events
4. Dispose of the job object

Before disposing of the job object, as described in Step 4, you should save the printing settings it contains so that the next time your user opens the document you can restore its printing settings. The recipe "Saving Printing Information" beginning on page 267 shows how you can save and restore printing information.

Functions Used in This Recipe

QuickDraw GX functions used in this recipe:

GXNewJob	"Core Printing Features" QuickDraw GX Printing
GXUpdateJob	"Advanced Printing Features" QuickDraw GX Printing
GXDisposeJob	"Core Printing Features" QuickDraw GX Printing

Standard Macintosh functions used in this recipe:

WaitNextEvent	"Event Manager" Macintosh Toolbox Essentials
FrontWindow	"Window Manager" Macintosh Toolbox Essentials

This recipe gives a brief description of these functions; you can find complete reference information for these functions in the Inside Macintosh suite of books.

Recipe Step Descriptions

In this section, each step is described individually.

1. Store printing information in your document information structure

   The QuickDraw GX job object stores printing-related information for a document. Since you have a job object for each open document, you can store a reference to it in its document information structure. For documents that allow multiple page formats, you can also store some other information in your document information structure as well.

   For example, this recipe adds these four printing-related fields to your document information structure:

   gxJob documentJob;
   gxFormat pageFormat[kMaxPages];
   long numPages;
   long curPage;

   The recipe uses these fields to store this information:

   • The documentJob field stores a reference to the document's job object.
   • The pageFormat field stores an array of references to format objects, which contains custom page formatting information for each page
     of the document. You can specify a nil value for entries in this array corresponding to pages in your document that use default page-
     formatting information.
   • The numPages field stores the current number of pages in the document.
   • The curPage field stores the page number of the page that the user is currently viewing.

2. Create a job object for your document

   Now that you have a place to store the reference to it, you can create the actual job object with the GXNewJob function. This recipe step creates a new job object and, if creating the job object causes no errors, stores a reference to the job object in the documentJob field of the document information structure referenced by the global variable gCurrent:

   err = GXNewJob(&newJob);

   if (err == noErr) {
       gCurrent->documentJob = newJob;
       /* Code to perform other initializations goes here */
   } else {
       /* Code to handle errors goes here */
   }

   This example handles the situation when the user is creating a new document. If the user is opening a saved document, rather than creating a new document, you should create a job object and then restore any printing information that you saved with the document. The recipe "Saving Printing Information" beginning on page 267 shows how you can save and restore printing information with your documents.

3. Update the job object in response to resume events

   With QuickDraw GX, the user can change certain types of printing information--such as the printing extension setup--while your application is suspended in the background. When the user resumes your application, you need to update all of the job objects for documents your application
   has open.

   QuickDraw GX provides the GXUpdateJob function for this situation. Whenever your application receives a resume event from the standard Macintosh function WaitNextEvent, you should call this function for all of your job objects. Here is an example that shows how you might do this:

   documentInfo *windowDocument;

   whichWindow = FrontWindow();

   while (whichWindow != nil) {

       if (MyWindowIsDocumentWindow(whichWindow) {
           windowDocument = MyGetDocumentPtr(whichWindow);
           GXUpdateJob(windowDocument->documentJob);

       }

       whichWindow = (WindowPtr) 
                     ((WindowPeek) whichWindow) -> nextWindow;
   }

   With this sample code, you need to provide

   • the MyWindowIsDocumentWindow function, which determines if the window is a document window
   • the MyGetDocumentPtr function, which returns a pointer to the document information record for the document displayed in the window

4. Dispose of the job object when you close the document

   When the user closes a document, you can dispose of its job object with the GXDisposeJob function:

   GXDisposeJob(gCurrent->documentJob);

   If the user chooses to save changes to the document when closing it, your application should also save the information contained in the document's job object. See the recipe "Saving Printing Information" beginning on page 267 for more information.

Related Recipes

For more information about printing with QuickDraw GX, see these recipes:

• "Handling Printing Dialog Boxes," described next, shows you how to display and respond to the printing dialog boxes.
• "Printing a Document With Custom Formats," beginning on page 264, shows how to print a document.
• "Saving Printing Information," beginning on page 267, shows how to save a job object.

The recipes in Chapter 4, "Using the QuickDraw GX Environment," show you how to initialize QuickDraw GX printing. You should read the recipes in that chapter before using the recipes in this chapter.